<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Percolate query | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="specialized-queries.html" title="Specialized queries">
<link rel="prev" href="query-dsl-mlt-query.html" title="More like this query">
<link rel="next" href="_notes_4.html" title="Notes">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="query-dsl.html">Query DSL</a></span>
»
<span class="breadcrumb-link"><a href="specialized-queries.html">Specialized queries</a></span>
»
<span class="breadcrumb-node">Percolate query</span>
</div>
<div class="navheader">
<span class="prev">
<a href="query-dsl-mlt-query.html">« More like this query</a>
</span>
<span class="next">
<a href="_notes_4.html">Notes »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="query-dsl-percolate-query"></a>Percolate query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h2>
</div></div></div>

<p>The <code class="literal">percolate</code> query can be used to match queries
stored in an index. The <code class="literal">percolate</code> query itself
contains the document that will be used as query
to match with the stored queries.</p>
<h3>
<a id="_sample_usage"></a>Sample Usage<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h3>
<p>Create an index with two fields:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my-index
{
    "mappings": {
        "properties": {
             "message": {
                 "type": "text"
             },
             "query": {
                 "type": "percolator"
             }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/238.console"></div>
<p>The <code class="literal">message</code> field is the field used to preprocess the document defined in
the <code class="literal">percolator</code> query before it gets indexed into a temporary index.</p>
<p>The <code class="literal">query</code> field is used for indexing the query documents. It will hold a
json object that represents an actual Elasticsearch query. The <code class="literal">query</code> field
has been configured to use the <a class="xref" href="percolator.html" title="Percolator type">percolator field type</a>. This field
type understands the query dsl and stores the query in such a way that it can be
used later on to match documents defined on the <code class="literal">percolate</code> query.</p>
<p>Register a query in the percolator:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my-index/_doc/1?refresh
{
    "query" : {
        "match" : {
            "message" : "bonsai tree"
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/239.console"></div>
<p>Match a document to the registered percolator queries:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "percolate" : {
            "field" : "query",
            "document" : {
                "message" : "A new bonsai tree in the office"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/240.console"></div>
<p>The above request will yield the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 13,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score": 0.26152915,
    "hits": [
      { <a id="CO50-1"></a><i class="conum" data-value="1"></i>
        "_index": "my-index",
        "_type": "_doc",
        "_id": "1",
        "_score": 0.26152915,
        "_source": {
          "query": {
            "match": {
              "message": "bonsai tree"
            }
          }
        },
        "fields" : {
          "_percolator_document_slot" : [0] <a id="CO50-2"></a><i class="conum" data-value="2"></i>
        }
      }
    ]
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO50-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The query with id <code class="literal">1</code> matches our document.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO50-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">_percolator_document_slot</code> field indicates which document has matched with this query.
Useful when percolating multiple document simultaneously.</p>
</td>
</tr>
</table>
</div>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>To provide a simple example, this documentation uses one index <code class="literal">my-index</code> for both the percolate queries and documents.
This set-up can work well when there are just a few percolate queries registered. However, with heavier usage it is recommended
to store queries and documents in separate indices. Please see <a class="xref" href="query-dsl-percolate-query.html#how-it-works" title="How it Works Under the Hood">How it Works Under the Hood</a> for more details.</p>
</div>
</div>
<h4>
<a id="_parameters_3"></a>Parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>The following parameters are required when percolating a document:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">field</code>
</p>
</td>
<td valign="top">
<p>
The field of type <code class="literal">percolator</code> that holds the indexed queries. This is a required parameter.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">name</code>
</p>
</td>
<td valign="top">
<p>
The suffix to be used for the <code class="literal">_percolator_document_slot</code> field in case multiple <code class="literal">percolate</code> queries have been specified.
This is an optional parameter.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">document</code>
</p>
</td>
<td valign="top">
<p>
The source of the document being percolated.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">documents</code>
</p>
</td>
<td valign="top">
<p>
Like the <code class="literal">document</code> parameter, but accepts multiple documents via a json array.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">document_type</code>
</p>
</td>
<td valign="top">
<p>
The type / mapping of the document being percolated. This parameter is deprecated and will be removed in Elasticsearch 8.0.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>Instead of specifying the source of the document being percolated, the source can also be retrieved from an already
stored document. The <code class="literal">percolate</code> query will then internally execute a get request to fetch that document.</p>
<p>In that case the <code class="literal">document</code> parameter can be substituted with the following parameters:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">index</code>
</p>
</td>
<td valign="top">
<p>
The index the document resides in. This is a required parameter.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">type</code>
</p>
</td>
<td valign="top">
<p>
The type of the document to fetch. This parameter is deprecated and will be removed in Elasticsearch 8.0.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">id</code>
</p>
</td>
<td valign="top">
<p>
The id of the document to fetch. This is a required parameter.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">routing</code>
</p>
</td>
<td valign="top">
<p>
Optionally, routing to be used to fetch document to percolate.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">preference</code>
</p>
</td>
<td valign="top">
<p>
Optionally, preference to be used to fetch document to percolate.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">version</code>
</p>
</td>
<td valign="top">
<p>
Optionally, the expected version of the document to be fetched.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="_percolating_in_a_filter_context"></a>Percolating in a filter context<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>In case you are not interested in the score, better performance can be expected by wrapping
the percolator query in a <code class="literal">bool</code> query’s filter clause or in a <code class="literal">constant_score</code> query:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "constant_score": {
            "filter": {
                "percolate" : {
                    "field" : "query",
                    "document" : {
                        "message" : "A new bonsai tree in the office"
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/241.console"></div>
<p>At index time terms are extracted from the percolator query and the percolator
can often determine whether a query matches just by looking at those extracted
terms. However, computing scores requires to deserialize each matching query
and run it against the percolated document, which is a much more expensive
operation. Hence if computing scores is not required the <code class="literal">percolate</code> query
should be wrapped in a <code class="literal">constant_score</code> query or a <code class="literal">bool</code> query’s filter clause.</p>
<p>Note that the <code class="literal">percolate</code> query never gets cached by the query cache.</p>
<h4>
<a id="_percolating_multiple_documents"></a>Percolating multiple documents<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>The <code class="literal">percolate</code> query can match multiple documents simultaneously with the indexed percolator queries.
Percolating multiple documents in a single request can improve performance as queries only need to be parsed and
matched once instead of multiple times.</p>
<p>The <code class="literal">_percolator_document_slot</code> field that is being returned with each matched percolator query is important when percolating
multiple documents simultaneously. It indicates which documents matched with a particular percolator query. The numbers
correlate with the slot in the <code class="literal">documents</code> array specified in the <code class="literal">percolate</code> query.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "percolate" : {
            "field" : "query",
            "documents" : [ <a id="CO51-1"></a><i class="conum" data-value="1"></i>
                {
                    "message" : "bonsai tree"
                },
                {
                    "message" : "new tree"
                },
                {
                    "message" : "the office"
                },
                {
                    "message" : "office tree"
                }
            ]
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/242.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO51-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The documents array contains 4 documents that are going to be percolated at the same time.</p>
</td>
</tr>
</table>
</div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 13,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score": 0.7093853,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "1",
        "_score": 0.7093853,
        "_source": {
          "query": {
            "match": {
              "message": "bonsai tree"
            }
          }
        },
        "fields" : {
          "_percolator_document_slot" : [0, 1, 3] <a id="CO52-1"></a><i class="conum" data-value="1"></i>
        }
      }
    ]
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO52-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">_percolator_document_slot</code> indicates that the first, second and last documents specified in the <code class="literal">percolate</code> query
are matching with this query.</p>
</td>
</tr>
</table>
</div>
<h4>
<a id="_percolating_an_existing_document"></a>Percolating an Existing Document<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>In order to percolate a newly indexed document, the <code class="literal">percolate</code> query can be used. Based on the response
from an index request, the <code class="literal">_id</code> and other meta information can be used to immediately percolate the newly added
document.</p>
<h5>
<a id="_example"></a>Example<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h5>
<p>Based on the previous example.</p>
<p>Index the document we want to percolate:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my-index/_doc/2
{
  "message" : "A new bonsai tree in the office"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/243.console"></div>
<p>Index response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "_index": "my-index",
  "_type": "_doc",
  "_id": "2",
  "_version": 1,
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "result": "created",
  "_seq_no" : 1,
  "_primary_term" : 1
}</pre>
</div>
<p>Percolating an existing document, using the index response as basis to build to new search request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "percolate" : {
            "field": "query",
            "index" : "my-index",
            "id" : "2",
            "version" : 1 <a id="CO53-1"></a><i class="conum" data-value="1"></i>
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/244.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO53-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The version is optional, but useful in certain cases. We can ensure that we are trying to percolate
the document we just have indexed. A change may be made after we have indexed, and if that is the
case the search request would fail with a version conflict error.</p>
</td>
</tr>
</table>
</div>
<p>The search response returned is identical as in the previous example.</p>
<h4>
<a id="_percolate_query_and_highlighting"></a>Percolate query and highlighting<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>The <code class="literal">percolate</code> query is handled in a special way when it comes to highlighting. The queries hits are used
to highlight the document that is provided in the <code class="literal">percolate</code> query. Whereas with regular highlighting the query in
the search request is used to highlight the hits.</p>
<h5>
<a id="_example_2"></a>Example<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h5>
<p>This example is based on the mapping of the first example.</p>
<p>Save a query:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my-index/_doc/3?refresh
{
    "query" : {
        "match" : {
            "message" : "brown fox"
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/245.console"></div>
<p>Save another query:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my-index/_doc/4?refresh
{
    "query" : {
        "match" : {
            "message" : "lazy dog"
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/246.console"></div>
<p>Execute a search request with the <code class="literal">percolate</code> query and highlighting enabled:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "percolate" : {
            "field": "query",
            "document" : {
                "message" : "The quick brown fox jumps over the lazy dog"
            }
        }
    },
    "highlight": {
      "fields": {
        "message": {}
      }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/247.console"></div>
<p>This will yield the following response.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 7,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 2,
        "relation": "eq"
    },
    "max_score": 0.26152915,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "3",
        "_score": 0.26152915,
        "_source": {
          "query": {
            "match": {
              "message": "brown fox"
            }
          }
        },
        "highlight": {
          "message": [
            "The quick &lt;em&gt;brown&lt;/em&gt; &lt;em&gt;fox&lt;/em&gt; jumps over the lazy dog" <a id="CO54-1"></a><i class="conum" data-value="1"></i>
          ]
        },
        "fields" : {
          "_percolator_document_slot" : [0]
        }
      },
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "4",
        "_score": 0.26152915,
        "_source": {
          "query": {
            "match": {
              "message": "lazy dog"
            }
          }
        },
        "highlight": {
          "message": [
            "The quick brown fox jumps over the &lt;em&gt;lazy&lt;/em&gt; &lt;em&gt;dog&lt;/em&gt;" <a id="CO54-2"></a><i class="conum" data-value="1"></i>
          ]
        },
        "fields" : {
          "_percolator_document_slot" : [0]
        }
      }
    ]
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO54-1"><i class="conum" data-value="1"></i></a><a href="#CO54-2"></a></p>
</td>
<td align="left" valign="top">
<p>The terms from each query have been highlighted in the document.</p>
</td>
</tr>
</table>
</div>
<p>Instead of the query in the search request highlighting the percolator hits, the percolator queries are highlighting
the document defined in the <code class="literal">percolate</code> query.</p>
<p>When percolating multiple documents at the same time like the request below then the highlight response is different:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "percolate" : {
            "field": "query",
            "documents" : [
                {
                    "message" : "bonsai tree"
                },
                {
                    "message" : "new tree"
                },
                {
                    "message" : "the office"
                },
                {
                    "message" : "office tree"
                }
            ]
        }
    },
    "highlight": {
      "fields": {
        "message": {}
      }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/248.console"></div>
<p>The slightly different response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 13,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score": 0.7093853,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "1",
        "_score": 0.7093853,
        "_source": {
          "query": {
            "match": {
              "message": "bonsai tree"
            }
          }
        },
        "fields" : {
          "_percolator_document_slot" : [0, 1, 3]
        },
        "highlight" : { <a id="CO55-1"></a><i class="conum" data-value="1"></i>
          "0_message" : [
              "&lt;em&gt;bonsai&lt;/em&gt; &lt;em&gt;tree&lt;/em&gt;"
          ],
          "3_message" : [
              "office &lt;em&gt;tree&lt;/em&gt;"
          ],
          "1_message" : [
              "new &lt;em&gt;tree&lt;/em&gt;"
          ]
        }
      }
    ]
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO55-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The highlight fields have been prefixed with the document slot they belong to,
in order to know which highlight field belongs to what document.</p>
</td>
</tr>
</table>
</div>
<h4>
<a id="_specifying_multiple_percolate_queries"></a>Specifying multiple percolate queries<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>It is possible to specify multiple <code class="literal">percolate</code> queries in a single search request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my-index/_search
{
    "query" : {
        "bool" : {
            "should" : [
                {
                    "percolate" : {
                        "field" : "query",
                        "document" : {
                            "message" : "bonsai tree"
                        },
                        "name": "query1" <a id="CO56-1"></a><i class="conum" data-value="1"></i>
                    }
                },
                {
                    "percolate" : {
                        "field" : "query",
                        "document" : {
                            "message" : "tulip flower"
                        },
                        "name": "query2" <a id="CO56-2"></a><i class="conum" data-value="1"></i>
                    }
                }
            ]
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/249.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO56-1"><i class="conum" data-value="1"></i></a><a href="#CO56-2"></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">name</code> parameter will be used to identify which percolator document slots belong to what <code class="literal">percolate</code> query.</p>
</td>
</tr>
</table>
</div>
<p>The <code class="literal">_percolator_document_slot</code> field name will be suffixed with what is specified in the <code class="literal">_name</code> parameter.
If that isn’t specified then the <code class="literal">field</code> parameter will be used, which in this case will result in ambiguity.</p>
<p>The above search request returns a response similar to this:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 13,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score": 0.26152915,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "1",
        "_score": 0.26152915,
        "_source": {
          "query": {
            "match": {
              "message": "bonsai tree"
            }
          }
        },
        "fields" : {
          "_percolator_document_slot_query1" : [0] <a id="CO57-1"></a><i class="conum" data-value="1"></i>
        }
      }
    ]
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO57-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">_percolator_document_slot_query1</code> percolator slot field indicates that these matched slots are from the <code class="literal">percolate</code>
query with <code class="literal">_name</code> parameter set to <code class="literal">query1</code>.</p>
</td>
</tr>
</table>
</div>
<h4>
<a id="how-it-works"></a>How it Works Under the Hood<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/percolate-query.asciidoc">edit</a>
</h4>
<p>When indexing a document into an index that has the <a class="xref" href="percolator.html" title="Percolator type">percolator field type</a> mapping configured, the query
part of the document gets parsed into a Lucene query and is stored into the Lucene index. A binary representation
of the query gets stored, but also the query’s terms are analyzed and stored into an indexed field.</p>
<p>At search time, the document specified in the request gets parsed into a Lucene document and is stored in a in-memory
temporary Lucene index. This in-memory index can just hold this one document and it is optimized for that. After this
a special query is built based on the terms in the in-memory index that select candidate percolator queries based on
their indexed query terms. These queries are then evaluated by the in-memory index if they actually match.</p>
<p>The selecting of candidate percolator queries matches is an important performance optimization during the execution
of the <code class="literal">percolate</code> query as it can significantly reduce the number of candidate matches the in-memory index needs to
evaluate. The reason the <code class="literal">percolate</code> query can do this is because during indexing of the percolator queries the query
terms are being extracted and indexed with the percolator query. Unfortunately the percolator cannot extract terms from
all queries (for example the <code class="literal">wildcard</code> or <code class="literal">geo_shape</code> query) and as a result of that in certain cases the percolator
can’t do the selecting optimization (for example if an unsupported query is defined in a required clause of a boolean query
or the unsupported query is the only query in the percolator document).  These queries are marked by the percolator and
can be found by running the following search:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "query": {
    "term" : {
      "query.extraction_result" : "failed"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/250.console"></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The above example assumes that there is a <code class="literal">query</code> field of type
<code class="literal">percolator</code> in the mappings.</p>
</div>
</div>
<p>Given the design of percolation, it often makes sense to use separate indices for the percolate queries and documents
being percolated, as opposed to a single index as we do in examples. There are a few benefits to this approach:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Because percolate queries contain a different set of fields from the percolated documents, using two separate indices
allows for fields to be stored in a denser, more efficient way.
</li>
<li class="listitem">
Percolate queries do not scale in the same way as other queries, so percolation performance may benefit from using
a different index configuration, like the number of primary shards.
</li>
</ul>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="query-dsl-mlt-query.html">« More like this query</a>
</span>
<span class="next">
<a href="_notes_4.html">Notes »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
